home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 26 / AMIGAplus Sonderheft 26 (2000)(Falke)(DE)(Track 1 of 2)[!].iso / libs / README < prev    next >
Text File  |  1999-03-29  |  20KB  |  444 lines

  1. README for ixemul.library and ixnet.library version 47.3
  2.  
  3.  
  4. IMPORTANT
  5. =========
  6.  
  7. Always read the NEWS file for information about new features! The NEWS file
  8. is part of the ixemul source archive.
  9.  
  10. Also look at the ix.h header: ixemul-specific functions are documented in that
  11. header.
  12.  
  13. Starting with ixemul.library version 42.0 the ssystem() function is no longer
  14. supported. The only two applications use this function are (to my knowledge)
  15. gcc and man. You should either upgrade to the latest gcc (2.7.2 or higher)
  16. or replace gcc by gccv (which is part of older gcc distributions). You can
  17. find a new 'man' version in Geek Gadgets.
  18.  
  19. Starting with ixemul.library version 43.1 various networking functions have
  20. been moved to libc.a. See the NEWS file for details. It only concerns
  21. certain somewhat specialized functions, so 'normal' clients and daemons
  22. shouldn't be affected.
  23.  
  24. Starting with ixemul.library version 46.0 some basic p.OS support has been
  25. added, which is completed in 47.0. See README.pOS for more details.
  26.  
  27. This library is part of Geek Gadgets.  For more information see
  28. ftp.ninemoons.com, /pub/geekgadgets.
  29.  
  30.  
  31.  
  32. INTRODUCTION
  33. ============
  34.  
  35. Originally created in 1991 or 1992 by Markus Wild, the ixemul.library has
  36. become the driving force behind the Geek Gadgets project.
  37.  
  38. Essentially it is a BSD Unix kernel running under the Amiga OS.  The
  39. code for handling Unix signals is taken almost verbatim from the BSD kernel
  40. sources, for example.  Multitasking and file I/O is, of course, passed on
  41. to the Amiga OS.  Because the library resembles BSD Unix so closely, it has
  42. made it possible to port almost all Unix programs.
  43.  
  44. However, because of the conformance to BSD, the library is not too
  45. conservative with resources or overly concerned with Amiga standards.  For
  46. example, command line expansion uses Unix semantics and doesn't use
  47. ReadArgs().  The purpose of ixemul.library is to emulate Unix as well as is
  48. technically possible.  So given a choice between Amiga behavior or Unix
  49. behavior, the last one is chosen.
  50.  
  51.  
  52.  
  53. HISTORY
  54. =======
  55.  
  56. As I mentioned, the library was originally created by Markus Wild.  It
  57. allowed him to port Unix programs, most notably gcc and a Unix shell
  58. (pdksh), which in turn gave him the opportunity to start porting NetBSD
  59. Unix.  At some point he stopped working on ixemul.library and continued
  60. with the real thing, NetBSD.
  61.  
  62. Although Markus made some snapshots of his library available on Internet,
  63. he was about the only one who could actually compile it.  The snapshots
  64. where never complete and didn't use a standard Make tool.
  65.  
  66. Rafael W. Luebbert managed around June 1994 to actually compile the
  67. library using bits and pieces from four different source releases.  Even
  68. then he had to write some missing code and had to debug a lot before he got
  69. it working.  Luebbert released versions 40.1 through 40.4.  Since this was
  70. the only version available that could actually be compiled, Fred Fish
  71. switched to version 40.4 for his FreshFish CDROM series.
  72.  
  73. Leonard Norrgard also started working on 40.4, fixing a variety of
  74. problems.  So for a time there were two versions of the library, both
  75. derived from 40.4.  Around March 1995 I began contributing my own fixes for
  76. the library to Fred, including a fix for a horrible memory trashing bug
  77. which substantially improved the stability of the library.  Starting with
  78. version 42.0 I became the new maintainer of the library.  I merged
  79. Leonard's version of the library into 42.0, the whole source distribution
  80. was cleaned up and reorganized and many bugs were fixed.  Also new
  81. functionality was added such as timezone support.
  82.  
  83. Thanks to Jeff Shepherd the support for network functions has been totally
  84. reorganized for version 43.0.  A new ixnet.library was introduced that
  85. contains all the network handling.  This new library supports both AS225
  86. and AmiTCP.  Furthermore, there is no longer any need to maintain two
  87. versions of an Internet client or daemon as ixnet.library will do the
  88. multiplexing for you.  The program itself is completely shielded from the
  89. actual networking package in use.  Also, should a new networking package
  90. appear for the Amiga, then it is relatively easy to add support for that
  91. package to ixnet.library.  All existing programs will automatically be able
  92. to work with the new package too.
  93.  
  94. Version 43.0 also introduced support for automatic stack extension
  95. (provided you compiled your program with the -mstackextend flag).  This
  96. support was done by Matthias Fleischer.
  97.  
  98. Last, but not least, I've added the ptrace() function, which was essential
  99. for porting the GNU debugger, GDB.  So it is now possible to use a decent
  100. debugger with gcc (and with the GNU C++, fortran and ADA compilers).
  101.  
  102. Version 43.1 was a bug-fix release, which further improved stability.
  103.  
  104. Version 44.0 made the library much more (Net)BSD compatible, making it even
  105. easier to port Unix programs. Also many bugs were fixed.
  106.  
  107. Version 45.0 fixed a few bugs, improved stack extension (see the new ixstack
  108. utility) and further improved Ctrl-C handling by adding 'sessions', something
  109. that was needed for the Geek Gadgets X port.
  110.  
  111. Version 45.1 was a bug-fix release, and also improved uid/gid handling.
  112.  
  113. Version 46.0 adds shared memory (shm*) and basic p.OS support.
  114.  
  115. Version 46.1 renames the __os variable to ix_os.
  116.  
  117. Version 47.0 completes the p.OS support and adds Unix semaphore and message
  118. support. Also fixes several bugs.
  119.  
  120. Version 47.1 fixes a minor but very irritating bug in the ixstack utility.
  121.  
  122. Version 47.2 is a bug-fix release.
  123.  
  124. Version 47.3 is a bug-fix release.
  125.  
  126.  
  127. USAGE
  128. =====
  129.  
  130. The Aminet distribution of ixemul consists of several archives:  one for
  131. each flavor (CPU/FPU combination) of the library, one for the timezone
  132. support, an archive for documentation, an archive for various utilities and
  133. an SDK archive, containing headers, libraries and C-objects that provide
  134. the startup code.  There is also an ixemul source archive.  If you don't
  135. mind recompiling everything, and if you have a decent Geek Gadgets
  136. environment, then all you have to do is retrieve this archive, as all the
  137. other archives are generated from this source distribution.
  138.  
  139. Besides the library itself, there are also some utilities and other
  140. goodies.  First of all, there is a special trace version of the library.
  141. Together with the ixtrace tool it allows you to see which library functions
  142. are called by the program you want to debug.  If you compile the library
  143. yourself you will also get, as part of the compile process, a debug version
  144. of the library.  If you get an Enforcer hit in the library, and if you have
  145. SegTracker installed, then you can track down in which source and at which
  146. line the hit took place using the gccfindhit tool (available from Aminet
  147. and Geek Gadgets) that is similar to the FindHit tool which is part of the
  148. Enforcer package.  I've used this with great success in the past.
  149.  
  150. Various settings that influence the behavior of the library can be set
  151. using the ixprefs utility.  A small tool ixrun allowing you to run AmigaOS
  152. scripts from within the Unix shell is also provided.  An ixemul-specific
  153. pipe-handler allows you to set up a pipe between an AmigaOS utility and an
  154. Unix program.  A pipe between two Unix programs is handled by the
  155. ixemul.library itself, but since AmigaOS programs are not under the
  156. control of the library, this handler is used instead.
  157.  
  158. A recent addition is the ixstack tool, which can list and set the minimum
  159. stack size an ixemul program needs.  It can also show the actual stack
  160. usage of ixemul programs if you start it with '-s'.
  161.  
  162. Finally, the tools zic (for manipulating the timezone databases) and
  163. ixtimezone are also part of ixemul.  The ixtimezone tool can be used to
  164. automatically adjust the Amiga time based on the currently selected
  165. timezone.  The best way to use this tool is to install the timezone
  166. databases (in etc:zoneinfo), set the TZ environment variable correctly (in
  167. my case "Europe/Amsterdam"), add the line "ixtimezone -patch-resource
  168. >nil:" to your user-startup and set the Amiga clock to Greenwich Mean Time
  169. (or Universal Time, as it is now called).  Now you will never have to worry
  170. about things like Daylight Saving Time as each time ixtimezone is called,
  171. this tool checks the current timezone and will patch the Amiga clock to the
  172. right time.  This tool is also very useful if you also run NetBSD or Linux,
  173. as these OSes expect that the internal Amiga clock adheres to GMT.
  174.  
  175. I advise that you set the ixemul "Network support" to the correct method
  176. using the ixprefs program. It will improve performance somewhat if ixemul
  177. doesn't have to guess which network library is available, if any.
  178.  
  179.  
  180.  
  181. MEMORY REQUIREMENTS
  182. ===================
  183.  
  184. The library itself needs about 200 Kb, but if you want to do some useful
  185. work, such as compiling programs, I advise at least 4 Mb.  More importantly
  186. is the stack size:  set it to at least 50 Kb. If you have problems with
  187. certain programs try to increase the stack size.
  188.  
  189. The reason for these large stacks is that the Unix operating system
  190. automatically extends the stack if it is too small. Therefore some Unix
  191. programs aren't exactly conservative with their stack space.
  192.  
  193. We can do the same on AmigaOS, however, by compiling programs with the
  194. -mstackextend flag. Or you can set the minimum stack size of a program
  195. using the ixstack tool. If the current stack is too small, the program will
  196. automatically extend the stack on startup.
  197.  
  198.  
  199.  
  200. PROGRAMMING WITH IXEMUL
  201. =======================
  202.  
  203. There is really very little to do.  If you have a decent Geek Gadgets setup
  204. with the necessary compilers and tools, and if you have installed the
  205. ixemul SDK, then you are ready to go.  There is no need to do anything
  206. special, the communication between your program and ixemul.library is
  207. handled by the startup code (the *crt0.o files in the /gg/lib directory)
  208. and the standard C library (libc.a, also in /gg/lib) which are
  209. automatically linked with your program.  Note that ixemul.library together
  210. with the compile tools also provides profiling support (compile and link
  211. with -pg), and base-relative and resident support (compile with -fbaserel
  212. or -resident).  Compile and link with -g to add debug information so that
  213. you can debug your program with gdb.
  214.  
  215. If you start gdb with the -enforcer option, then the program you are
  216. debugging will automatically stop and drop into the debugger as soon as an
  217. Enforcer hit occurs.  This is obviously very useful.
  218.  
  219. The startup code will automatically expand the command-line for you (e.g.
  220. 'echo *' will expand to 'echo <filenames in current directory>'). If you
  221. want to disable this in your program, then you should add the line:
  222.  
  223.     int ix_expand_cmd_line = 0;
  224.  
  225. to your source. This global variable will tell the system not to expand the
  226. command-line.
  227.  
  228. The startup code will also set the global "int ix_os;". This variable
  229. contains either 0 (= the program was started from an AmigaOS system) or 
  230. OS_IS_POS (0x704F5300), which means that the program was started from an
  231. p.OS system. See README.pOS for more information. The OS_IS_POS and
  232. OS_IS_AMIGAOS macros are defined in ix.h.
  233.  
  234. Code like you would on a Unix system, so DON'T USE any information
  235. private to the library!
  236.  
  237.  
  238.  
  239. PORTING UNIX PROGRAMS
  240. =====================
  241.  
  242. Most programs compile out-of-the-box.  There are a few exceptions to this
  243. rule.  First of all, programs like linkers and the like that have to be
  244. able to read or write the standard Amiga hunk format obviously need a lot
  245. of work.
  246.  
  247. Secondly, there is no virtual memory support, and therefore no real fork()
  248. function.  In most cases the fork() function is only used to spawn a new
  249. program, and in such cases it is possible to replace fork() by vfork(),
  250. which is a light-weight fork() replacement that was originally created for
  251. Unix to reduce the overhead a real fork() introduced.
  252.  
  253. A vfork() doesn't create a copy of itself as fork() does, but uses the
  254. parent's code and data.  Since the child will quickly call execve() to
  255. spawn another program, this sharing of the code and data is no problem and
  256. saves a lot of time.
  257.  
  258. There is one restriction, however: since the child process is running on
  259. the stack of the parent until an exit() or execve() call the child must be
  260. careful not to clobber the parent's stack. So this will fail:
  261.  
  262.       main()
  263.       {
  264.         switch (vfork())
  265.         {
  266.           case -1:      // Error
  267.           case 0:       // Child
  268.             return 0;    // Return from main()
  269.  
  270.           default:      // Parent
  271.             wait(0);
  272.             break;
  273.         }
  274.         
  275.         return 0;
  276.       }
  277.  
  278. It fails because the child just returns, and this return will clobber the
  279. stack for when the parent returns. But this is correct:
  280.  
  281.       main()
  282.       {
  283.         switch (vfork())
  284.         {
  285.           case -1:              // Error
  286.           case 0:               // Child
  287.             exit(0);            // Exit
  288.             break;
  289.  
  290.           default:              // Parent
  291.             wait(0);
  292.             break;
  293.         }
  294.         
  295.         return 0;
  296.       }
  297.  
  298. Here the child calls exit or execve and therefor leaves the underlying
  299. stack intact for the parent. This restriction can cause very hard to find
  300. bugs (I know, I spent quite a few hours researching this problem).
  301.  
  302. In some cases, such as a Unix shell (pdksh for example), you really want to
  303. be able to port a program that uses a fork() that cannot be replaced with
  304. vfork().  There is a way to do this, although it is a lot of work.  First
  305. of all, the program has to be compiled with -resident.  Now you replace the
  306. fork() by a ix_vfork() call, and in the child code you call vfork_setup_child()
  307. (new for 44.0!  Replaces the ix_resident()/ix_get_vars2() pair) to copy the
  308. original data hunk to a new location.  Next you have to copy all the
  309. parent's data structures to the child.  In other words, you have to copy
  310. the complete state of the parent process to the child process.  This can be
  311. a lot of work.  Finally, you call vfork_resume() which unblocks the parent
  312. so that you now have two processes running separately from each other.
  313.  
  314. It is important to realize that you should never exit() from the parent
  315. before all vfork()'ed children have died.  Since exiting from the parent
  316. causes the parents code and data segments to be deallocated, the child
  317. would find itself without code space to run on, and would probably cause a
  318. severe machine crash!
  319.  
  320. So always call at least `wait(0)' before returning from the parent.
  321.  
  322. For an example of how this works, see jobs.c from the pdksh source
  323. distribution.  It's a kind of poor-man's fork().
  324.  
  325. The third case I've come across that couldn't easily be ported were
  326. programs that dump their state to a new file.  Emacs does this, as does GNU
  327. Common Lisp.  The idea is that such a program will read lots of packages,
  328. and then dump itself to a new file.  That new file can in turn be executed,
  329. and you will no longer have to load all those packages.  All this assumes
  330. that each time you load a program, all the code and data ends up at the same
  331. memory addresses as before.  Something that is true for Unix, but not for
  332. the Amiga due to the lack of virtual memory.
  333.  
  334. However, if someone wants to do a port of such a program, please contact me
  335. as I have developed a technique to implement this.  At least, I've made
  336. this work with a small test program.  I've tried to use it with GNU Common
  337. Lisp, but time constraints prevented me from developing this further.
  338.  
  339. The last problematic category I've seen is GNU Emacs.  This program assumes
  340. that all the data it allocates will always end up in a continuous memory
  341. block, and that the upper 8 bits of each memory address are always the
  342. same.  The Amiga, however, can have multiple memory blocks positioned at
  343. various places in memory.  While there is a GNU Emacs port, this port does
  344. assume this limitation and if you have an Amiga with many memory blocks (as
  345. I had) GNU Emacs may easily crash.  No easy solution exists.
  346.  
  347.  
  348.  
  349. AMIGA PROGRAMMING & IXEMUL
  350. ==========================
  351.  
  352. If you use Amiga specific resources like Windows and Screens from
  353. Intuition, make sure to add an atexit() handler to close those resources,
  354. if the user should decide to interrupt your program.  Before the program is
  355. left, the chain of registered atexit-handlers is called in exit().  So
  356. PLEASE NEVER EVER call _exit() if you have registered any custom atexit()
  357. handlers.  It is a bad habit anyway, but normally you may call _exit()
  358. without resource lossage (stdio won't flush its buffers, but that's about
  359. all).
  360.  
  361. Ixemul provides a new unique Amiga specific signal called SIGMSG.  If you
  362. set up a handler for this signal, then the default mapping from
  363. SIGBREAKB_CTRL_C into SIGINT will no longer occur, and your handler is
  364. called with the following arguments:
  365.  
  366.   signal_handler(SIGMSG, new_exec_signal_mask)
  367.  
  368. In this case, you have to deal with Exec signals yourself, so don't forget
  369. to clear those signals that you want to receive notification about again
  370. later.  Thus if you'd want to handle SIGBREAKB_CTRL_C yourself, don't
  371. forget to
  372.  
  373.   SetSignal(0, SIGBREAKF_CTRL_C)
  374.  
  375. at the end of the handler, or you'll never get notification about that
  376. signal again.
  377.  
  378. Most of the original BSD signals are implemented.  SIGSTOP is currently not
  379. implemented, although it would be relatively easy to add.  The mechanisms
  380. are already in place.
  381.  
  382.  
  383.  
  384. HANDLING OF UID/GID IN IXEMUL.LIBRARY
  385. =====================================
  386.  
  387. The following information was provided by Norbert Pueschel:
  388.  
  389. Here is a list of functions that are concerned with uid/gid management
  390. and access to user/group information:
  391.  
  392. a) uid/gid management:
  393.    get(e)uid, set((r)e)uid, get(e)gid, set((r)e)gid, (init|set|get)groups
  394.  
  395. b) access to user/group informations:
  396.    set(pass|group)ent, (set|get|end)pwent, get(pw|gr)nam, getpwuid, getgrgid,
  397.    (_)getlogin, setlogin
  398.  
  399. c) other functions:
  400.    setsid, crypt
  401.  
  402.  
  403. Ixemul.library has several options how to implement these functions:
  404.  
  405. 1) When MultiUser is installed, ixemul.library will use it to implement the
  406.    functions named above.
  407.  
  408. 2) When MultiUser is _not_ installed, ixemul.library will use its own
  409.    uid/gid handling: uids and gids will be inherited by child processes
  410.    and files and directories created by ixemul using programs will have
  411.    the current user and group set as long as the filesystem supports that.
  412.    However, for file accesses only the setting of the flags for the file
  413.    owner is used (as for any other AmigaOS program).
  414.  
  415. Processes that are not started by other ixemul using programs use
  416. environment variables to determine their (e)uid and (e)gid:
  417.  
  418. They will first check the variables LOGNAME and USER for a valid user
  419. name. If they find this user in the passwd file, they will set up (e)uid
  420. and (e)gid respectively. Then the environment variables UID, EUID, GID and
  421. EGID will be queried, and, if present, their values will be used.
  422.  
  423. If none of the above variables is found, the process will be owned by
  424. nobody/nogroup (uid/gid -2).
  425.  
  426.  
  427. Ixemul.library has three different methods to get user/group
  428. informations:
  429.  
  430. a) If networking software (AmiTCP or Inet) is installed, it will use their
  431.    user/group databases.
  432.  
  433. b) If no networking is available, it will try to read the files etc:passwd
  434.    and etc:group.
  435.  
  436. c) If both a) and b) fails, it will use a builtin user/group database.
  437.    This database only knows the nobody/nogroup (uid/gid -2), root/wheel
  438.    (uid/gid 0) and a user/group combination described by the environment
  439.    variables LOGNAME or USER, GROUP, UID and GID.
  440.  
  441.                       Hans Verkuil (hans@wyst.hobby.nl, January 3, 1998)
  442.  
  443. (Parts of this README are from the original README by Markus Wild).
  444.